Migrate Yarn 4 PnP to pnpm 11, and repair the quality gates that were hiding - #268

Swaps the package manager without changing a single dependency version.
The lockfile was produced with `pnpm import`, which reads yarn.lock and
preserves its exact resolutions, so this commit changes the mechanism and
nothing about what resolves. Version changes land separately.

What goes away:
- 1,379 committed .yarn/cache zips (778 MB in the working tree). pnpm keeps
  one copy of each package in a global content-addressable store and
  hardlinks it into node_modules.
- .pnp.cjs, .pnp.loader.mjs and .yarn/sdks. With a real node_modules tree,
  Jest, ESLint, Next and tsserver resolve natively, so the editor SDK shim
  layer in .vscode/settings.json is deleted rather than ported.
- The .gitignore rules excluding *-win32-* and *-darwin-* cache archives.
  Those existed only because a developer installing on Windows would
  otherwise overwrite the linux binaries Vercel needed to deploy.

Configuration notes, all of which are pnpm 11 specifics that fail silently
if got wrong:
- pnpm 11 made .npmrc auth/registry-only. Every other setting lives in
  pnpm-workspace.yaml. Settings left in .npmrc are ignored without warning.
- `allowBuilds` replaced `onlyBuiltDependencies`, which pnpm 11 removed and
  now ignores. Config copied from any pnpm 10 guide looks right and does
  nothing.
- Yarn's `resolutions` became `overrides`, carried over verbatim.

Yarn ran every dependency install script (enableScripts: true). pnpm denies
all of them by default and takes an explicit allowlist, so this is a net
supply-chain improvement: four packages are allowed to run build scripts,
and a compromised release of anything else gets no install-time execution.

Also fixes two things the migration made unavoidable:
- `build` still carried `ls -la && ls -la .yarn` debug probes from a Vercel
  investigation; the .yarn probe now hard-fails.
- `test` was `jest --watch`. An interactive watcher under the conventional
  script name is a footgun that CLAUDE.md carried a standing warning about.
  `test` is now non-interactive; `test:watch` is the watcher.

The pre-commit hook has been disabled behind a "Commented out for Windows
development" note, with a .bat sibling meant to cover Windows that git never
invoked -- git runs .husky/pre-commit through sh on every platform. Both
hooks are now single cross-platform scripts and the dead .bat files are gone.

Verified: pnpm install (14.9s cold, warm store), typecheck, and a full
production build including service worker and sitemap (12.5s) all pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

Takes the repository from 53 known advisories to 5. All five that remain have
no upstream fix: postcss (4) and sharp (1) are already at the latest published
version, so nothing to move to.

Resolves the substance of the open Dependabot PRs, which cannot themselves
survive this branch -- they carry yarn.lock diffs and cannot rebase onto a
tree with no yarn.lock.

Direct bumps of note:
- next 16.2.6 -> 16.2.11 (#254)
- sharp 0.34.5 -> 0.35.3 (#252)
- react / react-dom 19.1 -> 19.2.8, @types to match
- @serwist/build 9.2.1 -> 9.5.12 (#213)
- jest-environment-jsdom 30.2.0 -> 30.4.1 (#215)
- postcss 8.5.10 -> 8.5.26 (#257), @babel/core (#241), and the rest of the
  patch-updates group (#265) via in-range `pnpm update`
- @testing-library/jest-dom 6.6.3 -> 7.0.1. pnpm flagged 6.10.0 as a
  mis-published minor carrying breaking changes; 7.x is the clean line and
  its @testing-library/dom peer range is already satisfied.

Transitive advisories (nanoid #264, brace-expansion #259, fast-uri #258,
js-yaml #256, ws #247, form-data #236, tar #229 (the one CRITICAL),
minimatch #228, follow-redirects #222) were resolved by letting `pnpm update`
move the parents that pin them, rather than by pinning each child directly.

That distinction is the point of the one override this adds:

    socks: ^2.8.9

ip-address had two advisories. The chain is socks -> ip-address, and socks
2.8.5 pins `ip-address: ^9`. Overriding ip-address to ^10 would have handed
socks an API it does not expect -- precisely the failure that killed coverage
when the inherited glob override reached test-exclude@6. socks 2.8.9 already
declares `ip-address: ^10.1.1`, so bumping the parent lets the fixed child
arrive legitimately. Fix the package that declares the bad range, not the
package named in the advisory.

Also drops @eslint/compat and @eslint/eslintrc, which became dead when the
FlatCompat layer was removed, and annotates one more real
`react-hooks/set-state-in-effect` hit that eslint-plugin-react-hooks 7.1
newly detects in PromptComposer. Like the OpioidConverter one it is described
rather than fixed: it changes when a user's manual edits are discarded, and
the component has no test coverage.

NOT included, deliberately: tailwindcss 3 -> 4 (#214). That is a real
migration -- a new config format and a rewritten cascade layer model -- with
visual consequences on every page, and it belongs in its own PR with a human
looking at the result.

Verified: lint clean, typecheck clean, 4/4 tests with coverage, production
build 14.2s.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

Vercel parses engines.node to choose a runtime and accepts a major selector,
not a semver range; ">=22.13.0" fails the build outright. Back to "22.x",
which still satisfies pnpm 11's own >=22.13 requirement.

Changed alone, deliberately: the preview deploy is the only instrument
available here (no Vercel CLI or token in this environment to read a build
log), so changing one variable per push is the only way to learn which one
matters.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

`packages: [.]` declared this single-package repo as a pnpm workspace root.
pnpm does not need it -- overrides and allowBuilds are still read, verified by
a clean --frozen-lockfile install that applies the socks override and runs the
allowed build scripts -- but it makes the repo look like a monorepo to tooling
that keys off pnpm-workspace.yaml, Vercel included.

Third single-variable attempt at the failing preview deploy. No Vercel CLI or
token exists in this environment, so the build log cannot be read and each
hypothesis has to be tested by pushing it alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

Pinning --webpack did not fix the preview deploy, so the builder is not
implicated and there is no reason to give up Turbopack's 2.4x faster build
(measured, both sides, in docs/PNPM-MIGRATION.md section 8).

Parking the Vercel failure here rather than continuing to guess. Four
hypotheses were each tested by pushing them alone, and each was wrong:

  1. corepack not enabled            -> restored ENABLE_EXPERIMENTAL_COREPACK=1
  2. engines.node semver range       -> back to the "22.x" major selector
  3. pnpm-workspace packages: [.]    -> removed the monorepo signal
  4. Turbopack failing on Vercel     -> pinned --webpack

Changes 1-3 are correct regardless and are kept; 4 is reverted here.

What is known: main and PR #267 both deploy successfully, and every commit on
this branch fails, so the cause is on this branch. GitHub Actions runs the
same install and the same production build on ubuntu and passes in ~60s, so
it is specific to the Vercel environment rather than to pnpm or the build.

What is needed: the build log, which cannot be read from here -- there is no
Vercel CLI and no token in this environment. One command answers it:

    npx vercel login && npx vercel inspect <deployment-url> --logs

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

Sweeps every tracked file that told a human or an agent to run `yarn`, and
adds docs/PNPM-MIGRATION.md as the single write-up of what happened.

docs/PNPM-MIGRATION.md is the substantive one. It covers what PnP was doing
and what replaced it, the three places pnpm 11 configuration can silently not
work, why the install-script allowlist is a security improvement rather than a
chore, the override rule the repo learned the hard way, everything the
migration exposed, measured before/after numbers, and the history-rewrite
runbook with its blast radius.

Rewritten rather than substituted:
- docs/Tooling.md: the entire "Yarn Plug'n'Play" chapter is replaced with a
  pnpm chapter, and the git-hygiene table no longer tells you to commit
  `.pnp.cjs` and `.yarn/sdks`. The PnP troubleshooting section becomes
  troubleshooting for the two failures that actually occur now -- phantom
  dependencies and ERR_PNPM_IGNORED_BUILDS.
- README.md: the "Package Manager: Executive Recommendation" section argued
  for exactly this migration, so it is replaced by a short account of what the
  migration bought, with the reasoning moved into the migration doc. Its
  central claim is worth preserving and is why the section is not simply
  deleted: **Turbopack will never support Yarn PnP**, so the App Router work
  was blocked behind this change.
- CLAUDE.md: the standing warning "Never run `yarn test` -- it is Jest watch
  mode" is gone, because `pnpm test` is now the non-interactive run. The
  watcher is `pnpm test:watch`, and that is what agents are told to avoid.

Restores a `lint:mdx` script. It was dropped when `--ext` was removed, but
five documents reference it and flat config takes a glob, so
`eslint "**/*.mdx"` is the direct equivalent. Verified it runs clean.

next.config.js keeps `eslint.ignoreDuringBuilds: true`, now with a comment
explaining why. The README asked to "turn it back on"; that TODO is satisfied
by lint being its own CI job rather than by the flag. Making `next build` lint
again would run ESLint twice per PR and blame the build step for lint
failures.

README TODO entries completed by this branch are removed rather than left to
rot: the pnpm migration itself, the `ls -la .yarn` build prefix, the
contradictory `engines.yarn`, `test:ci`, and the missing CI workflow. The
`.yarn/cache` history purge stays open and now points at the runbook.

Verified: lint, lint:mdx, typecheck and 4/4 tests all clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

Does the two things in the order the risk demanded. The previous commit
annotated this as a known issue precisely because it is a medical dosing
calculator with no test coverage; this adds the coverage first and only then
touches the component.

1. `calculateTotals` is extracted into utils/calculations.ts **verbatim**. No
   arithmetic changed. It exists so the numbers can be asserted without
   rendering.

2. 22 characterisation tests pin the behaviour. They are explicitly NOT a
   clinical review -- they assert what the calculator does today so that a
   refactor can prove it moved nothing.

3. The component drops `morphineEq`/`methadoneEq` state and the effect that
   re-synced them, and computes with `useMemo` during render instead. That was
   a second render pass on every keystroke. The eslint-disable added earlier is
   gone with it.

The tests were mutation-checked rather than merely observed passing. Flipping
the Methadone branch from squaring to multiplying turns 3 red; deriving
methadone from the rounded rather than the unrounded total turns 4 red. A suite
never seen to fail is not evidence.

Writing them surfaced three behaviours that are PINNED, NOT ENDORSED. Each
looks like a bug, none is changed, because whether they are bugs is a clinical
question:

- **Methadone is special-cased to dose squared**, not `dose * toMorphine`.
  Methadone's potency really is non-linear in daily dose, so a special case is
  expected -- but this particular curve is unverified.
- **Methadone's `toMorphine: 0.25` is dead data.** The squaring branch never
  reads it, so editing that number has no effect whatsoever. A test asserts
  this, so wiring it back in fails loudly instead of silently changing every
  methadone conversion.
- **The two outputs round inconsistently.** `morphineEq` is the rounded total;
  `methadoneEq` derives from the UNROUNDED total. At 3 mg of codeine the UI
  shows 0 mg morphine equivalent beside 1 mg methadone equivalent.

Also: the branch matches `display === 'Methadone'` exactly, so any other
spelling silently takes the multiply path.

None of the above is a regression introduced here -- all of it predates this
branch and is now visible instead of implicit.

Verified: lint, typecheck, 22/22 tests, production build.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

A fresh Opus agent was briefed to refute this work rather than approve it. It
found real defects, including three claims I had made that were wrong. Fixing
the substantive ones and correcting the false statements.

**Advisories: 5 -> 0.** docs/PNPM-MIGRATION.md claimed the five remaining
advisories had "no upstream fix." That was false. Both packages had published
fixes and this project already depended on fixed versions directly; the
vulnerable copies (postcss@8.4.31, sharp@0.34.5) were dragged in transitively
by next. The fix is the technique §5 of that same document teaches -- override
the version so the old transitive copy cannot resolve -- applied to the one
case in the tree where it clears everything. `pnpm audit` now reports no known
vulnerabilities. Verified against the lockfile (zero references to either old
version) and by resolving postcss from inside next, which sees 8.5.26. Lint,
typecheck, tests and a production build all pass with the overrides in place.

**The pre-commit hook was reporting success for changes it never tested.**
next/jest does not translate tsconfig `paths` into a Jest moduleNameMapper.
Runtime resolution survives through the SWC transform, but Jest's static
dependency graph does not, so `jest --findRelatedTests` returned ZERO matches
for every @/-aliased module -- including the dosing calculator this branch
exists to protect. lint-staged runs that with `--passWithNoTests`, which turns
"found no tests" into a green tick. Adding the mapper takes
`--findRelatedTests calculations.ts` from 0 tests to 18.

**Coverage was flattering by 3.7x.** With no `collectCoverageFrom`, coverage
was computed over the 14 modules some test happened to import, out of 41.
OpioidConverter.tsx -- the file this branch refactored -- was absent from the
table entirely. Configured properly, the honest number is 13.47%, not 49.33%.

**CI could pass a commit to main with no completed run.** Both workflows set
`cancel-in-progress: true` on pushes to main. A cancelled run is not a failure
and shows no red X, so two merges landing close together could leave a commit
on main ungated. Cancellation is now conditioned off the default branch.

**Two documentation files were never committed,** including
src/resources/LLMPrompts.mdx, which RENDERS ON THE LIVE SITE and still told
readers to run `yarn install` against a yarn.lock this branch deletes. The
previous docs commit claimed to sweep every yarn reference; it missed these.

Corrections to claims made earlier on this branch:

- The mutation evidence in §7.1 was overstated. The second mutant turns
  **1 test red, not 4**. The original measurement was taken while the first
  mutant was still applied, because the restore step had silently failed, so
  three of those four failures belonged to the other mutation. This matters:
  the rounding asymmetry is pinned by a single assertion pair, because every
  other test uses integer totals where rounding is a no-op.
- "22 tests pin it" was the whole-repo count. The module has 18.
- §2 claimed parity with `pnpMode: strict` on phantom imports. That holds at
  the project root but not inside the store: pnpm's default
  `hoistPattern: ["*"]` hoists 787 packages where any package can reach them.
  `hoistPattern: []` would restore full strictness; it is recorded as a known
  gap rather than changed here, because it alters resolution for every package
  in the tree and needs its own verification pass.

Not addressed here, and left in the review's own words in HANDOFF.md: the
NaN coercion path in the converter's text input, two contradictory drug tables
(OPIOID_OPTIONS is dead code and disagrees with MEDICATION_ARRAY), and three
weak assertions in the new suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY

The adversarial review flagged that `handleDoseChange` does `Number(value)` on
a `type="text"` input, so anything typeable reaches the arithmetic, and none of
it had coverage. Six tests pin what currently happens.

All six document behaviour that is wrong-looking, and none is changed here --
the fix belongs at the input, not in the arithmetic, and it is a UI decision:

- Typing a letter yields NaN, which survives rounding and the sum, so the
  component renders "Morphine Equivalence: NaN mg".
- One bad field poisons the whole total, discarding every other dose entered.
- `0x10` is silently accepted as 16 and `5e3` as 5000 -- three orders of
  magnitude from what was typed.
- A negative dose is accepted and produces a NaN methadone equivalent, because
  sqrt of a negative is NaN.
- An empty field coerces to 0, which is the one sensible case.

Pinned rather than fixed so that whoever repairs the input has a concrete
failing-test target and can see exactly which behaviours move.

28 tests, lint and typecheck clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013RtsQWaEaAe4iVnSoUCDfY